Walkthrough

Documentation update to AGENTS.md introducing build/test command references, extending working rules with conductor-exec guidance, and adding conductor compatibility details explaining non-interactive shell behavior and tool version usage.

Changes

Conductor Execution and Compatibility Guidance

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• shakacode/react-webpack-rails-tutorial#737: Both PRs update documentation to standardize running project tools via bin/conductor-exec in non-interactive/CI contexts.

Poem

A rabbit hops through docs with glee, 🐰
Conductor paths for agents to see,
Run these commands, no system tools near,
Let bin/conductor-exec be crystal clear! ✨

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Review app commands

• +review-app-deploy - create or redeploy this PR's review app.
• +review-app-delete - delete this PR's review app and temporary resources.
• +review-app-help - show setup details and workflow behavior.

For setup details, comment +review-app-help.

Code Review — PR #739: Document Conductor command wrapper

Overall: This is a clean, low-risk documentation PR. The content is accurate (verified against bin/conductor-exec) and fills a real gap for non-Claude agents (Codex, GPT) working in the repo. A few issues worth addressing before merging:

Issues

1. Build command section is inconsistent with the wrapper guidance

The ## Build and Test Commands section shows bare commands (bundle exec rspec, etc.), but the Conductor Compatibility section added later says those exact commands should be run through bin/conductor-exec. An agent reading top-to-bottom could run the unwrapped versions before reaching the warning. Either:

• Add a note directly in the build commands block pointing to bin/conductor-exec, or
• Show the wrapped forms in that section (matching how CLAUDE.md handles this via the Solution block)

2. Missing version-number examples in symptoms list

CLAUDE.md includes concrete version numbers in the symptom list (e.g., "returns system Ruby (e.g., 2.6.10) instead of project Ruby (e.g., 3.4.3)"). This detail is helpful — it lets an agent recognise the problem immediately from tool output. Consider adding similar specificity to AGENTS.md.

3. Missing reference link

CLAUDE.md links to react_on_rails-demos#105 as background reading. Omitting it from AGENTS.md is fine if intentional, but the link provides useful context for anyone investigating the issue further.

4. Missing inline comment on git commit example

The bin/conductor-exec source file itself includes # Pre-commit hooks work correctly on the git commit example line. CLAUDE.md repeats it. AGENTS.md drops it. It explains why you'd wrap git commit, which isn't obvious — worth keeping.

Minor Nit

The added Working Rules bullet ("Run Ruby, Bundler, Node, pnpm, and git hook-sensitive commands through bin/conductor-exec...") references "non-interactive shells", but the full explanation of what that means doesn't appear until the Conductor Compatibility section below it. This ordering is fine but the bullet would be clearer if it said "in Conductor" instead of "in non-interactive shells", since that's the specific context.

Positives

• The fallback wording ("falls back to direct execution for non-mise users") is actually more accurate than CLAUDE.md's equivalent, which implies asdf/rbenv/nvm are natively supported — they aren't; the script just does exec "$@" and those managers only work if their shims are in PATH at the system level.
• Prose is concise and readable.
• No runtime code is touched; risk is purely documentation drift.

✅ Review app for PR #739 is deleted

Open organization console
View workflow logs

Code Review

PR: [codex] Document Conductor command wrapper
Type: Documentation only (AGENTS.md)
Risk: Low — no runtime code paths changed

Overview

This PR adds two sections to AGENTS.md: a build/test command reference and a Conductor compatibility guide explaining why bin/conductor-exec is needed in non-interactive shells. The content is accurate and follows the pattern already established in CLAUDE.md.

Issues

1. Inconsistency between the two new sections (medium)

The Build and Test Commands section documents commands without the bin/conductor-exec prefix:

bundle exec rspec
bundle exec rubocop

But the Working Rules bullet immediately below instructs agents to run Ruby/Bundler commands through bin/conductor-exec. An AI agent (or developer) scanning only the commands section will run them bare, which is exactly the failure mode the Conductor section warns against. The commands section should either use the wrapper or add a note pointing to the Conductor section.

2. Misleading fallback description (low)

The wrapper uses mise exec when mise is available and falls back to direct execution for non-mise users.

For users of asdf, rbenv, nvm, or nodenv, the fallback is exec "$@" — plain direct execution — which also runs without the correct PATH in a non-interactive shell. The description implies the fallback works for those users, but it silently uses the system version instead. CLAUDE.md handles this more carefully by listing those tools explicitly. Consider aligning the wording.

3. bundle exec rspec missing from wrapper examples (low)

The Conductor examples show bundle exec rubocop but not bundle exec rspec. Since tests are a primary CI command and appear in the commands section, they should be in the wrapper examples for completeness.

4. ruby --version as a "Use" example (nit)

bin/conductor-exec ruby --version is a diagnostic command, not a typical workflow step. It reads oddly alongside bundle exec rubocop and git commit. It is useful in the Symptoms section of CLAUDE.md but does not need to anchor the before/after example block here.

Positives

• Clear problem/symptom/solution structure mirrors CLAUDE.md and will be easy for agents to parse.
• Before/after code block is a practical pattern that reduces ambiguity.
• Keeping this change isolated to docs (no JS formatting noise) was the right call per the PR notes.

Greptile Summary

This PR updates AGENTS.md with a build/test command quick reference and detailed guidance on using bin/conductor-exec when working inside Conductor's non-interactive shell environment.

• Adds a Build and Test Commands section with bin/dev, RSpec, and RuboCop invocations.
• Adds a Conductor Compatibility section explaining why bin/conductor-exec is needed (non-interactive shell skips .zshrc/mise PATH setup) with before/after examples and a mise exec fallback note.
• Adds a Working Rules bullet requiring all Ruby/Bundler/Node/pnpm/git-hook commands to go through bin/conductor-exec.

Confidence Score: 4/5

Safe to merge — documentation-only change with no runtime impact.

The quick-reference commands in the new Build and Test Commands section show bare bundle exec invocations, while the Working Rules bullet added in the same commit explicitly says those commands must go through bin/conductor-exec. A developer following only the quick reference will reproduce the exact environment mismatch the document is trying to prevent.

AGENTS.md — the quick-reference block and the Working Rules bullet are inconsistent with each other.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer runs command] --> B{Using bin/conductor-exec?}
    B -- Yes --> C{mise available?}
    C -- Yes --> D[mise exec -- command\nCorrect tool versions from .tool-versions]
    C -- No --> E[Direct execution\nfallback for asdf/rbenv/nvm users]
    B -- No --> F{Interactive shell?}
    F -- Yes --> G[.zshrc sourced\nmise PATH active\nCommand works correctly]
    F -- No --> H[Conductor non-interactive shell\n.zshrc NOT sourced\nmise PATH NOT active]
    H --> I[System Ruby/Node used\nVersion mismatch\nPre-commit hooks may fail]

_{Reviews (1): Last reviewed commit: "Document conductor command wrapper" | Re-trigger Greptile}